{literal}
<h2>Annotation</h2>
@orm has|owns history $className inverse $inveresPropertyName<br>
<br>
History plugin helps in situation where you need to create change history on certain objects.<br />
<br />
NB! History plugin usage should be really thought through if you want to store relations in history! There might be situations where restoring from history might create situation where related objects doesn't exist anymore.

<h2>Sample</h2>

For sample we have created simple situation where we have Item class which has title and description. It is also related to one User.
ItemHistory class is used to store property values.
<br />

<pre class="code">
&lt;?php
class Item extends DomArObject {

	/**
	* @orm text
	*/
	public $title;
	/**
	* @orm longtext
	*/
	public $description;
	/**
	 * @orm has parent User inverse items
	 */
	public $user;
	/**
	 * @orm has history ItemHistory inverse item
	 */
	public $history;
}

class User extends DomArObject {
	
	/**
	* @orm text
	*/
	public $username;
	/**
	 * @orm has many Item inverse user
	 */
	public $items;
}

class ItemHistory extends DomArHistoryItem {
	
	/**
	 * @orm text
	 */
	public $title;
	/**
	 * @orm longtext
	 */
	public $description;
	/**
	 * @orm int(11)
	 * @orm listener beforeValidate beforeValidateUser
	 */
	public $user;
	/**
	 * @orm has parent Item inverse history
	 */
	public $item;
	
	public function beforeValidateUser( &$value ) {
		if( is_object($value) )
			return $value->id;
		else
			return $value;
	}
	
	public function getUserRestoreValue() {
		return User::load($this->user);
	}
		
}
?&gt;
</pre>

<h2>Creating some sample data</h2>
<pre class="code">
&lt;?php

$u1 = new User();
$u1->username = 'Balduran';
$u1->save();

$u2 = new User();
$u2->username = 'Oliver';
$u2->save();

$a = new Item();
$a->title = 'My title';
$a->description = 'My description';
$a->user = $u1;
$a->save();

// this change will save first history item with version nr 1.
// That history item title will be "My title"
$a->title = 'My changed title';
$a->user = $u2;
$a->save();

// this change will save second history item with version nr 2.
// That history item title will be "My changed title"
$a->title = 'My changed title again';
$a->save();

?&gt;
</pre>
<h2>Working with history</h2>
<pre class="code">
&lt;?php
echo $a->history->getLastVersionNr() // 2
echo $a->title; // My changed title again


// Restoring from previous history items.
$a->history->restoreFrom( 1 );
$a->save(); 
// as we changed our object, new history item will be created.
echo $a->history->getLastVersionNr() // 3
echo $a->title; // My title



// accessing older history objects
$ver2 = $a->history->getVersion( 2 );
echo $ver2->title; // My changed title

// Notice that $a->history is instanceof DomArHistory object. 
// This object extends to DomArSet witch means that all usual 1:N relationship methods are available!
foreach( $a->history->query()->orderBy('t.version')->commit() as $historyItem )
	echo $a->history->version.' ';
// outputs 1 2 3


?&gt;
</pre>
{/literal}